General Modding Guide
Interface Principles The game interfaces are created using Scaleform, which allows us to take Flash 8 files and use the as game interface. However, in order to optimise performance, a lot of the flash is actually loading image files, usually .dds files. The interface is found in \Data\Interface In this directory are : : \Bits : \Cfg : \DDSTexture : \Fonts : \Icons : \Panels : \Screens : \Video Now, first the easiest folders and work our way up : Video and Fonts contain any videos and the game fonts. “'Screens'” describe the game screens : The intro, the main menu, the main game view, and so on. These are described using LUA files. Usually these have OnOpen() and OnClose() functions that are called when the screens are initialised. A screen can show one or several Panels (which are stored in the Panels directory), these Panels are usually started in the OnOpen function of the screen, using a call like this : Interface:OpenPanel("SOMEPANELNAME") Now, Panels have 2 files : *A gfx file, which is the export of the Flash file (and Actionscript) generated by the scaleform exporter *A .lua file which is used as “glue” between the interface and the code. So for instance in Data\Interface\Panels\Planet there is *Planet.gfx *Planet.lua Now, here is the start of the S_PLANET.lua screen file :. S_PLANET = {} function S_PLANET:OnOpen() InterfaceMgr.CurrentScreen ="PLANET" PLANET:HideRessourceLayer() Interface:OpenPanel("PLANET") PLANET:OnPanelOpen() PLANET:Init() Interface:OpenPanel("PLANET") is what opens and shows the Planet.gfx file, and the other PLANET:functionName() calls are functions in Planet.lua that are being called when the S_PLANET screen is being opened. For each of these Panel files, there is the possibility to define a function that will be called when the game loop is called. This function is of the form PANELNAME:OnUpdate(). However for a lot of these functions, there is simply a call to the main interface loop manager, called InterfaceMgr, which manages the different processes going on in the interface. For instance, for Planet.lua, the OnUpdate function is as follows : function PLANET:OnUpdate() InterfaceMgr:UpdateInPlanet() end Incidentally, that is also where the InterfaceMgr.CurrentScreen ="PLANET" comes from, it is telling InterfaceMgr what state the game is in. You won’t find InterfaceMgr in the main Interface directory, it is in fact in the script directory (Data\Design\Script) in the Interface sub-directory. Panels can load up smaller files which are also Flash / Scaleform exports, these smaller elements are called “Bits” and are in the Bits subdirectory of the main Interface directory. These are usually called something like _Bits_PaneName.gfx In general these are smaller panels that serve a specific purpose or are not the main screen panel. For instance, in the Planet.gfx panel, we load in : _Bits_FindCities.gfx (the “search cities” pane) _Bits_MapFilter.gfx (the map selection pane) _Bits_MyCities.gfx (the list of my cities) and so on. Each of these (Panels & Bits) can load in dds files. These files are to be found in Data\Interface\DDSTexture The files are DDS files, either DXT1a or DXT5 format. The button files are in Data\Interface\DDSTexture\Buttons Media Reports “Media reports” are what we call the text appearing to the top in the center of the screen showing the status of the city. These reports are generated by a set of LUA files (in \Data\Design\Scripts\MediaReports) Building description files (.class) Al the buildings in the game as described using a xml type file with a “.class” extension. Putting buildings in the game : The construction menu, buildings, and tags When starting up, the game parses all the .class files in the buildings directory (Data\Design\Buildings) and adds them to the game, in the construction menu. Where the buildings appear in the construction menu depends on how the building has been tagged : the construction menu is in fact a search engine, where each button is a tag and the buildings that appear are those that have the corresponding tags. At the root of the game there is a Tags.cfg file (in XML type format), which is where the tags are defined. There are mainly 3 different types of tags : *Functional tags, that describe what kind of building this is in the game simulation (e.g. Residence) *Size tags, which describe in which size category the building fits (T1, T2, T3, T3) *Wealth tags, mostly for residences and industries Other tags you will encounter *“MS18” - we used MSxx verionning tags to mark buildings that were compliant with the latest version of the code, and this was the last version. Buildings must be tagged with this to appear in the game *“Deprecated” - this is used to remove the building from the construction menu, without having to delete the .class file which will corrupt any saved cities that contained this building *“GemCity” - at one point we were working on other types of gameplay (Ski resort, beach resort) but we never got round to finishing them. These other gameplays had specific tags, and this tag is used to identify this building as not being part of these other side gameplays. *“PRIVATE” used to identify buildings that are a part of the City’s budget, or not If you open this file, you will see that some tags have children, and in the same way, the construction menu has sub categories, for instance “Factory” is a child of “Industry”. When adding a tag to a building with a tag, you will usually want to add all the parent tags too, because the construction menu works by drilling down functional categories (so in this case the menu allows you first to select “Industry”, and then “Factory”, so as both are selected in the menu the building needs to have both tabs to be seen). This rule is for functional tags (what the building does) and does not apply to wealth and size tags. A .class file in detail Here is a sample file for a building in the game, you can find it in full in the annex. I’ll walk you through every section View Section BuildingSelection &B_IND_NP02_T2 &B_IND_NP02_T2_SIM &B_IND_NP02_T2_DES &B_IND_NP02_T2_PARAM1 &B_IND_NP02_T2_VALUE1 &B_IND_NP02_T2_PARAM2 &B_IND_NP02_T2_VALUE2 &B_IND_NP02_T2_PARAM3 &B_IND_NP02_T2_VALUE3 This section determines how the building is shown in the interface *Panel : describes which panel will be called to display the building information. Not sure if this is plugged in or if the pannel is hardcoded. *Loc keys : The text that will be shown in the construction menu & selection panel, used to set the building name, type description, and so on Display Section Data/Gfx/Building/b_ind_np02new_t2.sgbin Data/Gfx/Placeholder/b_aaind_t2.sgbin 1 "" 0 "" Array_PollutionAir This section describes the 3d objects used to show the building in the game: *The main element is le “Model” node, which describes which sgbin (3d object) file is used *Placeholder does not need to be changed, it is a fallback 3d model used in developpment (when the final sgbin was not yet available) *Fundament : **Use: does the 3d model have a “foundation” : Most buildings have a square basis and terraform the landscape, if the building doesn’t need to terraform this can be set to 0 (false) **Model : the model used for the foundation, usually doesn’t need to be changed *Edit mode Only : Can this building be used in the game, or only in the editor (e.g. is it a static decoration) *Thumb : Used to define the thumbnail that will be shown in the game’s construction menu. If left empty, this will revert to a filename based on the model name (in this case, b_ind_np02new_t2.dds) *SelectionLayer : This defines which simulation Layer is to be shown when the building is selected. In this case, the Air Pollution Layer. Placement Section BUILDING TERRAIN "" 1 0 "" 1 1 0.3000000119 15 0 60 20 0 LFRE_0 The placement section defines how a building is to be placed : *The “Type” node determines which type of algorithm is to be called to do the placement. BUILDING is the default mode, you won’t need to change this in most cases. Roads & surface buildings (like the garbage dump) use other placement types *Delegate Prototype, : this was used by surface buildings (like the garbage dump) to say: when people ask to place me, use another prototype instead *Terraform/Enable : Does this placement mode support terraforming ? *LayerDisplay : Which Layer should be displayed when placing the building. In this case it is the Freight ( LFRE_0) layer. Layouts The layout of a building determines where the different decorations (trees, cars, characters, etc.) are placed within the building, and whether an offset in height needs to be applied to this layout 0 Data/Design/Layout/B_Service/b_ind_np02_t2_Base.layout EntityPosition This is data used in the placement algorithm. : EntityPosition\CollisionShape\Dimension is the space the building occupies on the floor (in meters) 40,40 20.12739944 1 1 1 0 Tags Industry;Factory;T2;MS18;GemCity;PRIVATE;Manufacturing Tags have already been described earlier in the document, they determine where the building will appear in the construction menu. Entity This identifies the behavior components that are to be used by the building. In this case : *BUILDING : this is a basic company, i.e. not a residence and not a road. Use “RESIDENCE” instead for residences. *SCZCOJOBPROVIDER : this building is a job provider, i.e. it employs citizens. This component impacts others, i.e. if the building is unable to find employees, it will not produce, or make money.. *SCCORESOURCEAGENT : this building is a resource agent, it consumes and produces resources *SLACOLAYER : this building impacts simulation layers (e.g. emits pollution, etc.) These components have sections in the .class file that are associated with them. BUILDING 0 SCZCOJOBPROVIDER SCCORESOURCEAGENT SLACOLAYER Job Provider Describes which type of “Cultures” (the term is inherited from City Life) the building employs (LowLive, AllAm,Suit, Elite ), and how attractive these jobs are to citizens of these wealth groups: 1 2 1 10 10 10 Resource Component This section describes the resources the building consumes and produces : : In each node of the form MaxProduction\Production1 .. :: ResourceName : the resource produced :: ResourceNumber : the amount produced :: ResourceUnitMinPriceBenef : the profits produced : In each node of the form MaxRequirement\Requirement1 :: ResourceName: The resource consumed :: ResourceNumber : the amount of resource consumed RIN2_0 300 17 RELE_0 24 ROFF_0 60 RIN1_0 160 Layer Component The building had a layer component, which is how the buildings impact each other geographically.There are various types of layers, and buildings impact Simulation Layers using different “Shapes”. Other layers include stuff like quality of life, noise, population density and so on. The interface to the right side of the screen allows you to visualise on screen a certain number of these layers. In our case, the layer is air pollution, and there are two impacts : one circular and one global to the whole map. PollutionAir 800 0 1 CIRCLE 1 PollutionAir 20000 0.01 0.01 ALLMAP 1 The Building (Budget Agent) component This determines how the economy aspect of the building works : how much the building can gain (MaxMonthlyBenefit), how much it can loose (MaxMonthlyDeficit), its basic functionning costs (UpkeepCost) and so on so on. Of note is the fact that the building can be impacted by other layers, as described in the “Sensitivity” node seen below. “IsPublicBuilding” determines whether the building’s economy is directly imputed to the city’s, or whether it is only indirectly imputed via taxes. 0 2680 -7130 3190 no 0 LFRE_0 9 1 The conditions node The conditions node determines under what conditions the building is visible and available in the construction menu. These conditions include the players ability to pay for the construction (ConstructionCost) The VisibleConditions are the conditions which determine whether the building is visible in the construction menu. In this case : “MinNbBuildingOnMapWithTagsRelock1” : There needs to be at least one building with the tags “GemCity” & “TownHall” before the building is visible. This is a basic setting which most buildings have, so that players can start placing the town hall before placing anything else (the economy is build in such a way that the town hall and all in one buildings are required to kickstart the economy). You can limit the number of buildings of a certain type on the map, by locking buildings if the number of buildings with a certain tag configuration goes beyond a certain threshold. The UnlockConditions are the conditions under which the building can be placed by the player. In our case, there also needs to be a town hall for the building to be unlocked, but there is also an unlock condition on the number of citizens (NbCitizen). This number is the number of simulation agents in the simulation, not the number of citizens visible in the interface. player_lock_all 4000 400 GemCity TownHall 1 1075 GemCity TownHall 1 player_lock_achievement 4000 400 Resources List Nothing included in Focus documentation here Layers List Nothing included in Focus documentation here Full Class file BuildingSelection &B_IND_NP02_T2 &B_IND_NP02_T2_SIM &B_IND_NP02_T2_DES &B_IND_NP02_T2_PARAM1 &B_IND_NP02_T2_VALUE1 &B_IND_NP02_T2_PARAM2 &B_IND_NP02_T2_VALUE2 &B_IND_NP02_T2_PARAM3 &B_IND_NP02_T2_VALUE3 Data/Gfx/Building/b_ind_np02new_t2.sgbin Data/Gfx/Placeholder/b_aaind_t2.sgbin 1 "" 0 "" Array_PollutionAir BUILDING TERRAIN "" 1 0 "" 1 1 0.3000000119 15 0 60 20 0 LFRE_0 0 Data/Design/Layout/B_Service/b_ind_np02_t2_Base.layout 40,40 20.12739944 1 1 1 0 Industry;Factory;T2;MS18;GemCity;PRIVATE;Manufacturing BUILDING 0 SCZCOJOBPROVIDER SCCORESOURCEAGENT SLACOLAYER 1 2 1 10 10 10 RIN2_0 300 17 RELE_0 24 ROFF_0 60 RIN1_0 160 PollutionAir 800 0 1 CIRCLE 1 PollutionAir 20000 0.01 0.01 ALLMAP 1 0 2680 -7130 3190 no 0 LFRE_0 9 1 player_lock_all 4000 400 GemCity TownHall 1 1075 GemCity TownHall 1 player_lock_achievement 4000 400 Category:Modding